// Pigeon Interface Definition for Android PTP API
// 
// This file defines the type-safe platform channel interface between Dart and Kotlin.
// 
// Generation Command:
//   dart run pigeon --input pigeons/android_ptp_api.dart
// 
// Output Files:
//   - Dart:   lib/src/pigeon/android_ptp_api.g.dart
//   - Kotlin: android/src/main/kotlin/com/example/ptp_wrapper/AndroidPtpApi.kt
// 
// Version: 1.0.0
// Date: 2025-10-27

import 'package:pigeon/pigeon.dart';

@ConfigurePigeon(PigeonOptions(
  dartOut: 'lib/src/pigeon/android_ptp_api.g.dart',
  dartOptions: DartOptions(),
  kotlinOut: 'android/src/main/kotlin/com/xxpie/ptp_wrapper/AndroidPtpApi.kt',
  kotlinOptions: KotlinOptions(
    package: 'com.xxpie.ptp_wrapper',
  ),
))

// ============================================================================
// Data Classes
// ============================================================================

/// 设备基本信息
///
/// 映射自 Android PTP 库的 DeviceInfo.java
class PtpDeviceInfo {
  final String manufacturer;        // 制造商
  final String model;               // 型号
  final String deviceVersion;       // 固件版本
  final String serialNumber;        // 序列号（用于唯一标识）
  final int vendorExtensionID;      // 厂商扩展 ID（用于 objectFormat → MimeType 转换）

  PtpDeviceInfo({
    required this.manufacturer,
    required this.model,
    required this.deviceVersion,
    required this.serialNumber,
    required this.vendorExtensionID,
  });
}

/// 文件详细信息
///
/// 映射自 Android PTP 库的 ObjectInfo.java
class PtpFileInfo {
  final int handle;                  // 文件句柄（PTP 协议）
  final int storageId;               // 存储设备 ID
  final int objectFormat;            // 对象格式代码（PTP 标准）
  final int protectionStatus;        // 保护状态（0=未保护）
  final int objectCompressedSize;    // 文件大小（字节）
  final String filename;             // 文件名
  final String? captureDate;         // 拍摄时间（ISO 8601 格式）
  final int imagePixWidth;           // 图片宽度（像素）
  final int imagePixHeight;          // 图片高度（像素）

  PtpFileInfo({
    required this.handle,
    required this.storageId,
    required this.objectFormat,
    required this.protectionStatus,
    required this.objectCompressedSize,
    required this.filename,
    this.captureDate,
    required this.imagePixWidth,
    required this.imagePixHeight,
  });
}

/// 存储设备信息
///
/// 映射自 Android PTP 库的 StorageInfo.java
class PtpStorageInfo {
  final int storageId;               // 存储设备 ID
  final int storageType;             // 存储类型（PTP 标准）
  final int filesystemType;          // 文件系统类型
  final int accessCapability;        // 访问能力（0=读写, 1=只读）
  final int maxCapacity;             // 最大容量（字节）
  final int freeSpaceInBytes;        // 可用空间（字节）
  final String? storageDescription;  // 存储描述
  final String? volumeLabel;         // 卷标

  PtpStorageInfo({
    required this.storageId,
    required this.storageType,
    required this.filesystemType,
    required this.accessCapability,
    required this.maxCapacity,
    required this.freeSpaceInBytes,
    this.storageDescription,
    this.volumeLabel,
  });
}

/// 连接状态
///
/// 映射自 Android PTP 库的 ConnectState.kt
enum PtpConnectionStatus {
  idle,              // 空闲（未连接）
  connecting,        // 连接中
  connected,         // 已连接
  disconnecting,     // 断开中
  disconnected,      // 已断开
  error,             // 错误
}

/// 错误信息
class PtpError {
  final int code;                    // 错误码
  final String message;              // 错误描述
  final String? details;             // 详细信息（可选）

  PtpError({
    required this.code,
    required this.message,
    this.details,
  });
}

// ============================================================================
// Host API (Dart calls Kotlin)
// ============================================================================

/// Android PTP API - Dart 调用 Kotlin 的接口
///
/// 由 Kotlin 端实现（AndroidPtpApiImpl），Dart 端调用
@HostApi()
abstract class AndroidPtpApi {
  // ------------------------------------------------------------------------
  // Device Management
  // ------------------------------------------------------------------------

  /// 获取设备信息
  ///
  /// Throws: PtpError if device not connected
  @async
  PtpDeviceInfo getDeviceInfo();

  /// 释放资源
  @async
  void dispose();

  // ------------------------------------------------------------------------
  // File Operations
  // ------------------------------------------------------------------------

  /// 获取文件句柄列表（分页）
  ///
  /// [storageId] 存储设备 ID
  /// [offset] 偏移量（从 0 开始）
  /// [limit] 每页数量
  ///
  /// Returns: 文件句柄列表（可能为空）
  /// Throws: PtpError if storage not found or operation failed
  @async
  List<int> getFileHandles(int storageId, int offset, int limit);

  /// 获取文件总数
  ///
  /// [storageId] 存储设备 ID
  ///
  /// Returns: 文件总数
  /// Throws: PtpError if storage not found
  @async
  int getFileCount(int storageId);

  /// 获取文件详细信息
  ///
  /// [handle] 文件句柄
  ///
  /// Returns: 文件详细信息
  /// Throws: PtpError if handle invalid or file not found
  @async
  PtpFileInfo getFileInfo(int handle);

  /// 批量获取文件信息（优化版）
  ///
  /// [handles] 文件句柄列表
  ///
  /// Returns: 文件信息列表（顺序与输入一致）
  /// Throws: PtpError if any handle invalid
  @async
  List<PtpFileInfo> batchGetFileInfo(List<int> handles);

  /// 获取文件缩略图
  ///
  /// [handle] 文件句柄
  ///
  /// Returns: 缩略图原始字节数据（JPEG 格式）
  /// Throws: PtpError if handle invalid or thumbnail not available
  @async
  Uint8List getFileThumbnail(int handle);

  /// 下载文件到本地
  ///
  /// [handle] 文件句柄
  /// [savePath] 本地保存路径
  ///
  /// Throws: PtpError if handle invalid or write failed
  ///
  /// Note: 进度通过 PtpEventListener.onDownloadProgress 回调
  @async
  void downloadFile(int handle, String savePath);

  /// 删除文件
  ///
  /// [handle] 文件句柄
  ///
  /// Throws: PtpError if handle invalid or delete failed
  @async
  void deleteFile(int handle);

  // ------------------------------------------------------------------------
  // Storage Management
  // ------------------------------------------------------------------------

  /// 获取存储设备列表
  ///
  /// Returns: 存储设备 ID 列表（可能为空）
  /// Throws: PtpError if device not connected
  @async
  List<int> getStorageList();

  /// 获取存储设备信息
  ///
  /// [storageId] 存储设备 ID
  ///
  /// Returns: 存储设备详细信息
  /// Throws: PtpError if storage not found
  @async
  PtpStorageInfo getStorageInfo(int storageId);
}

// ============================================================================
// Flutter API (Kotlin calls Dart)
// ============================================================================

/// PTP Event Listener - Kotlin 回调 Dart 的接口
///
/// 由 Dart 端实现，Kotlin 端调用
@FlutterApi()
abstract class PtpEventListener {
  // ------------------------------------------------------------------------
  // Connection Events
  // ------------------------------------------------------------------------

  /// 连接状态变化
  ///
  /// [status] 新的连接状态
  /// [error] 错误信息（仅在 status=error 时有值）
  void onConnectionStatusChanged(PtpConnectionStatus status, PtpError? error);

  // ------------------------------------------------------------------------
  // File Events
  // ------------------------------------------------------------------------

  /// 文件新增事件
  ///
  /// [handle] 新增文件的句柄
  void onFileAdded(int handle);

  /// 文件删除事件
  ///
  /// [handle] 被删除文件的句柄
  void onFileRemoved(int handle);

  // ------------------------------------------------------------------------
  // Download Progress
  // ------------------------------------------------------------------------

  /// 下载进度更新
  ///
  /// [handle] 文件句柄
  /// [downloaded] 已下载字节数
  /// [total] 文件总字节数
  void onDownloadProgress(int handle, int downloaded, int total);

  /// 下载完成
  ///
  /// [handle] 文件句柄
  /// [path] 本地保存路径
  void onDownloadComplete(int handle, String path);

  /// 下载错误
  ///
  /// [handle] 文件句柄
  /// [error] 错误信息
  void onDownloadError(int handle, PtpError error);
}

// ============================================================================
// Error Codes Reference
// ============================================================================

/// 常见错误码定义（仅供参考，不生成代码）
///
/// 1001: DEVICE_NOT_CONNECTED - 设备未连接
/// 1002: INVALID_HANDLE - 无效的文件句柄
/// 1003: INVALID_STORAGE_ID - 无效的存储 ID
/// 1004: FILE_NOT_FOUND - 文件不存在
/// 1005: PERMISSION_DENIED - 权限不足
/// 1006: TIMEOUT - 操作超时
/// 1007: NETWORK_ERROR - 网络错误（WIFI 连接）
/// 1008: STORAGE_FULL - 存储空间不足
/// 1009: HANDLE_RESET_DETECTED - 检测到 Handle 重置
/// 2001: PTP_GENERAL_ERROR - PTP 通用错误
/// 2002: PTP_PARAMETER_NOT_SUPPORTED - 参数不支持
/// 2003: PTP_OPERATION_NOT_SUPPORTED - 操作不支持
/// 2004: PTP_STORE_NOT_AVAILABLE - 存储不可用
/// 2005: PTP_OBJECT_WRITE_PROTECTED - 对象写保护

